%-------------------------------------------------------
% SLEPc Users Manual
%-------------------------------------------------------

\documentclass[titlepage,10pt,a4paper]{book}

\usepackage{xcolor}
\usepackage{graphicx}
\usepackage[square]{natbib}
\usepackage{fancyhdr}
\usepackage{fancyvrb}
\usepackage{caption}
\usepackage{xspace}
\usepackage{ae,aecompl}
\usepackage{amsmath,amssymb}
\usepackage{imakeidx}
\usepackage{hyperref}
\usepackage{titlesec}
\usepackage{tikz}

\makeindex

\hypersetup{
  colorlinks,
  linkcolor=purple,
  citecolor=violet,
  filecolor=blue,
  urlcolor=magenta,
  bookmarksnumbered,
  pdfstartview=FitH,
  pdftitle={SLEPc Users Manual},
  pdfauthor={J. E. Roman, C. Campos, L. Dalcin, E. Romero, A. Tomas},
  pdfsubject={SLEPc: Scalable Library for Eigenvalue Problem Computations},
  pdfkeywords={SLEPc, PETSc, eigenvalue problems}
}

\newcommand{\slepcversion}{3.15}
\newcommand{\slepchome}{https://slepc.upv.es}
\newcommand{\pack}[1]{{\sc #1}\index{\textsc{#1}}\xspace}
\newcommand{\packnoi}[1]{{\sc #1}\xspace}
\newcommand{\slepc}{\texorpdfstring{\packnoi{slep\rm c}}{{SLEPc}}}
\newcommand{\petsc}{\pack{pets\rm c}}
\newcommand{\blas}{\pack{blas}}
\newcommand{\lapack}{\pack{lapack}}
\newcommand{\arpack}{\pack{arpack}}
\newcommand{\parpack}{\pack{parpack}}
\newcommand{\trlan}{\pack{trlan}}
\newcommand{\primme}{\pack{primme}}
\newcommand{\blopex}{\pack{blopex}}
\newcommand{\scalapack}{\pack{scalapack}}
\newcommand{\elpa}{\pack{elpa}}
\newcommand{\elemental}{\pack{elemental}}
\newcommand{\evsl}{\pack{evsl}}
\newcommand{\feast}{\pack{feast}}
\newcommand{\mpich}{\pack{mpich}}
\newcommand{\expokit}{\pack{expokit}}
\newcommand{\rutina}[1]{\texttt{#1}\index{\texttt{#1}}}
\newcommand{\ident}[1]{\texttt{#1}\index{\texttt{#1}}}
\newcommand{\findex}[1]{\index{\texttt{#1}}}

\DeclareMathOperator{\rev}{rev}

%VerbatimEnvironment%
\fvset{numbers=left,numbersep=6pt,stepnumber=5}
\newcommand{\MyVerbatimInput}[1]{\fvset{fontsize=\scriptsize}%
  \VerbatimInput{#1}%
  \fvset{fontsize=\normalsize}%
}

\setlength{\textwidth}{14.5cm}
\setlength{\tabcolsep}{2mm}
\renewcommand{\arraystretch}{1.05}
\setcounter{tocdepth}{3}
\renewcommand{\captionlabelfont}{\sl\sffamily}
\makeatletter\@ifundefined{bibfont}{\newcommand{\bibfont}{\small}}{\renewcommand{\bibfont}{\small}}\makeatother

\titleformat{\chapter}[display]
  {\bfseries\Large}
  {\filleft\setlength{\fboxsep}{2mm}\fbox{\large\sc\chaptertitlename}\hspace*{-0.5mm}\setlength{\fboxsep}{4mm}\setlength{\fboxrule}{.5mm}\fbox{\Huge\bfseries\thechapter}}
  {4ex}
  {\huge\bf\sffamily
   \filright}
  [\hfill\rule{10cm}{1pt}]

\begin{document}

\title{
 	\vspace*{-1cm}
	\framebox[12cm][l]{
	\includegraphics[height=1.4cm]{figures/upv}
	\hfill
	\parbox[b]{4cm}{\begin{flushright}\vspace*{-7mm}\normalsize\sl\sffamily
	Departamento de\\[-0.8mm] Sistemas Inform\'aticos\\[-0.8mm]
	y Computaci\'on\\[0.8mm]
	\vspace{-2.5mm}\end{flushright}}
	\raisebox{3mm}{\includegraphics[height=9mm,width=1.4cm]{figures/dsic}}
	}
	\\[2cm]
	\normalsize Technical Report DSIC-II/24/02
	\\[2cm]
	\vspace*{6mm}
	{\Large\bf\sffamily
	SLEPc Users Manual\\[2mm]}
	{\large\bf\sffamily
	Scalable Library for Eigenvalue Problem Computations}\\[2mm]
	\vspace*{6mm}
	\vspace*{6mm}
	\url{\slepchome}
	\\[6mm]
}

\author{
  Jose E. Roman\\
  Carmen Campos\\
  Lisandro Dalcin\\
  Eloy Romero\\
  Andr\'es Tom\'as\\[3mm]
}

\date{
	To be used with \slepc \slepcversion\\
	March, 2021
}

\hypersetup{pageanchor=false}
\begin{titlepage}
\maketitle
\end{titlepage}

\setlength{\textheight}{18cm}
\setlength{\oddsidemargin}{0.6cm}
\setlength{\evensidemargin}{0.6cm}
\setlength{\footskip}{2cm}
\setlength{\voffset}{1.3cm}

\pagestyle{empty}
\cleardoublepage
\hypersetup{pageanchor=true}

{
  \pagestyle{plain}
  \pagenumbering{roman}
%---------------------------------------------------
\subsection*{Abstract}

	This document describes \slepc, the {\em Scalable Library for Eigenvalue Problem Computations}, a software package for the solution of large sparse eigenproblems on parallel computers. It can be used for the solution of various types of eigenvalue problems, including linear and nonlinear, as well as other related problems such as the singular value decomposition (see a summary of supported problem classes on page \pageref{tab:modules}). \slepc is a general library in the sense that it covers both Hermitian and non-Hermitian problems, with either real or complex arithmetic.

	The emphasis of the software is on methods and techniques appropriate for problems in which the associated matrices are large and sparse, for example, those arising after the discretization of partial differential equations. Thus, most of the methods offered by the library are projection methods, including different variants of Krylov and Davidson iterations. In addition to its own solvers, \slepc provides transparent access to some external software packages such as \packnoi{arpack}. These packages are optional and their installation is not required to use \slepc, see \S\ref{sec:wrap} for details. Apart from the solvers, \slepc also provides built-in support for some operations commonly used in the context of eigenvalue computations, such as preconditioning or the shift-and-invert spectral transformation.

	\slepc is built on top of \packnoi{pets\rm c}, the Portable, Extensible Toolkit for Scientific Computation \citep{Balay:2021:PUM}. It can be considered an extension of \packnoi{pets\rm c} providing all the functionality necessary for the solution of eigenvalue problems. This means that \packnoi{pets\rm c} must be previously installed in order to use \slepc. \packnoi{pets\rm c} users will find \slepc very easy to use, since it enforces the same programming paradigm. Those readers that are not acquainted with \packnoi{pets\rm c} are highly recommended to familiarize with it before proceeding with \slepc.


\subsubsection*{How to Get \slepc}

	All the information related to \slepc can be found at the following web site:
	\begin{quote}
	\begin{center}
	\url{\slepchome}.
	\end{center}
	\end{quote}
	The distribution file is available for download at this site. Other information is provided there, such as installation instructions and contact information. Instructions for installing the software can also be found in \S\ref{sec:inst}.

	\packnoi{pets\rm c} can be downloaded from \url{https://www.mcs.anl.gov/petsc}.  \packnoi{pets\rm c} is supported, and information on contacting support can be found at that site.

\subsubsection*{Additional Documentation}

	This manual provides a general description of \slepc. In addition, manual pages for individual routines are included in the distribution file in hypertext format, and are also available on-line at \url{\slepchome/documentation}. These manual pages provide hyperlinked access to the source code and enable easy movement among related topics. Finally, there are also several hands-on exercises available, which are intended for learning the basic concepts easily.

\subsubsection*{How to Read this Manual}

	Users that are already familiar with \packnoi{pets\rm c} can read chapter \ref{cap:int} very fast. Section \ref{sec:eig} provides a brief overview of eigenproblems and the general concepts used by eigensolvers, so it can be skipped by experienced users. Chapters \ref{cap:eps}--\ref{cap:mfn} describe the main \slepc functionality. Some of them include an advanced usage section that can be skipped at a first reading. Finally, chapter \ref{cap:add} contains less important, additional information.

\subsubsection*{What's New}

The major changes in the Users Manual with respect to the previous version are:
\begin{itemize}
\setlength{\itemsep}{-2pt}
\item New section \S\ref{sec:gsvd} related to the generalized singular value decomposition (GSVD). The rest of Ch.~\ref{cap:svd} has been slightly modified to cover the new GSVD functionality.
\end{itemize}

\subsubsection*{\slepc Technical Reports}

	The information contained in this manual is complemented by a set of Technical Reports, which provide technical details that normal users typically do not need to know but may be useful for experts in order to identify the particular method implemented in \slepc. These reports are not included in the \slepc distribution file but can be accessed via the \slepc web site. A \hyperlink{str}{list of available reports} is included at the end of the Bibliography.


\subsubsection*{Acknowledgments}

	We thank all the \packnoi{pets\rm c} team for their help and support. Without their continued effort invested in \packnoi{pets\rm c}, \slepc would not have been possible.
% We also thank Osni Marques and Tony Drummond for helping us raise awareness of \slepc in the context of the ACTS project.

	The current version contains code contributed by:
A.\ Lamas Davi\~{n}a (CUDA code),
Y.\ Maeda, T.\ Sakurai (CISS solvers),
M.\ Moldaschl, W.\ Gansterer (BDC subroutines),
F.\ Kong (nonlinear inverse iteration),
H.\ Fang, Y. Saad (\textsc{filtlan} polynomial filter).

	Development of \slepc has been partially funded by the following grants:
\begin{itemize}
\setlength{\itemsep}{-2pt}
\item Agencia Estatal de Investigaci\'on (Spain), grant no.\ PID2019-107379RB-I00, PI: Jos\'e E. Rom\'an.
\item Agencia Estatal de Investigaci\'on (Spain), grant no.\ TIN2016-75985-P, PI: Jos\'e E. Rom\'an.
\item Ministerio de Econom\'{\i}a y Comp.\ (Spain), grant no.\ TIN2013-41049-P, PI: Jos\'e E. Rom\'an.
\item Ministerio de Ciencia e Innovaci\'on (Spain), grant no.\ TIN2009-07519, PI: Jos\'e E. Rom\'an.
\item Valencian Regional Government, grant no.\ GV06/091, PI: Jos\'e E. Rom\'an.
\item Valencian Regional Government, grant no.\ CTIDB/2002/54, PI: Vicente Hern\'andez.
\end{itemize}

\subsubsection*{License and Copyright}

Starting from version 3.8, \slepc is released under a 2-clause BSD license (see \texttt{LICENSE} file).

\begin{quote}
\begin{sffamily}
Copyright 2002--2021 Universitat Polit\`ecnica de Valencia, Spain
\end{sffamily}
\end{quote}

%---------------------------------------------------
\newpage
\subsubsection*{Supported Problem Classes}

The following table provides an overview of the functionality offered by \slepc, organized by problem classes.

\begin{table}[h]
\label{tab:modules}
\centering
{\small \begin{tabular}{lccc}
Problem class                 & Model equation  & Module       & Chapter \\\hline
Linear eigenvalue problem     & $Ax=\lambda x,\quad Ax=\lambda Bx$ & \texttt{EPS} & \ref{cap:eps} \\
Quadratic eigenvalue problem  & $(K+\lambda C+\lambda^2M)x=0$ & -- & -- \\
Polynomial eigenvalue problem & $(A_0+\lambda A_1+\cdots+\lambda^dA_d)x=0$ & \texttt{PEP} & \ref{cap:pep} \\
Nonlinear eigenvalue problem  & $T(\lambda)x=0$ & \texttt{NEP} & \ref{cap:nep} \\\hline
Singular value decomposition  & $Av=\sigma u$   & \texttt{SVD} & \ref{cap:svd} \\
Matrix function (action of)   & $y=f(A)v$   & \texttt{MFN} & \ref{cap:mfn} \\
Linear matrix equation        & $AXE+DXB=C$   & \texttt{LME} & See notes \\\hline
\end{tabular} }
\end{table}

\noindent In order to solve a given problem, one should create a solver object corresponding to the solver class (module) that better fits the problem (the less general one; e.g., we do not recommend using \texttt{NEP} to solve a linear eigenproblem).\\[3mm]

\noindent Notes:\vspace{-2mm}
\begin{itemize}
\setlength{\itemsep}{-2pt}
\item Most users are typically interested in linear eigenproblems only.
\item In each problem class there may exist several subclasses (problem types in \slepc terminology), for instance symmetric-definite generalized eigenproblem in \texttt{EPS}.
\item The solver class (module) is named after the problem class. For historical reasons, the one for linear eigenvalue problems is called \texttt{EPS} rather than \texttt{LEP}.
\item The \texttt{SVD} module also supports the GSVD in addition to the SVD shown in the table.
\item In previous \slepc versions there was a \texttt{QEP} module for quadratic eigenproblems. It has been replaced by \texttt{PEP}. %See \S\ref{sec:qeppep} for upgrading application code that used \texttt{QEP}.
\item For the action of a matrix function (\texttt{MFN}), in \slepc we focus on methods that are closely related to methods for eigenvalue problems.
\item The solver class \texttt{LME} is still experimental and it is not covered in this manual yet.
\end{itemize}

%---------------------------------------------------
  \setlength{\parskip}{0cm}
  \tableofcontents
}
\cleardoublepage
\pagenumbering{arabic}
\pagestyle{fancy}
\renewcommand{\chaptermark}[1]{\markboth{\scriptsize \sffamily {\bfseries\chaptername\ \thechapter.} #1}{}}
\renewcommand{\sectionmark}[1]{\markright{\scriptsize \sffamily {\bfseries\thesection.} #1}{}}
\fancyhead{}
\fancyhead[LE,RO]{\nouppercase{\rightmark}}
\fancyhead[LO,RE]{\nouppercase{\leftmark}}
\fancyfoot[C]{\scriptsize --- \thepage\ ---}
\renewcommand{\headrulewidth}{0.2pt}
\renewcommand{\footrulewidth}{0.2pt}

\include{intro}
\include{eps}
\include{st}
\include{svd}
\include{pep}
\include{nep}
\include{mfn}
\include{extra}

%---------------------------------------------------
\cleardoublepage
\fancyhead{}\fancyhead[LO,RE]{\nouppercase{\scriptsize \sffamily Bibliography}}
\addcontentsline{toc}{chapter}{Bibliography}

%\bibliographystyle{engnat}
%\bibliography{slepc}
\input{slepc.bbl}

{\bibfont
\paragraph{SLEPc Technical Reports}
\hypertarget{str}{}
(Note: these reports are available through the \href{https://slepc.upv.es}{\slepc web site}.)
\begin{list}{}{\setlength{\labelwidth}{3cm}\setlength{\leftmargin}{12.5mm}}
\item[\textrm{\sffamily[STR-1]}] V. Hern\'andez, J. E. Rom\'an, A. Tom\'as, V. Vidal. ``Orthogonalization Routines in \slepc.''
\item[\textrm{\sffamily[STR-2]}] V. Hern\'andez, J. E. Rom\'an, A. Tom\'as, V. Vidal. ``Single Vector Iteration Methods in \slepc.''
\item[\textrm{\sffamily[STR-3]}] V. Hern\'andez, J. E. Rom\'an, A. Tom\'as, V. Vidal. ``Subspace Iteration in \slepc.''
\item[\textrm{\sffamily[STR-4]}] V. Hern\'andez, J. E. Rom\'an, A. Tom\'as, V. Vidal. ``Arnoldi Methods in \slepc.''
\item[\textrm{\sffamily[STR-5]}] V. Hern\'andez, J. E. Rom\'an, A. Tom\'as, V. Vidal. ``Lanczos Methods in \slepc.''
\item[\textrm{\sffamily[STR-6]}] V. Hern\'andez, J. E. Rom\'an, A. Tom\'as, V. Vidal. ``A Survey of Software for Sparse Eigenvalue Problems.''
\item[\textrm{\sffamily[STR-7]}] V. Hern\'andez, J. E. Rom\'an, A. Tom\'as, V. Vidal. ``Krylov-Schur Methods in \slepc.''
\item[\textrm{\sffamily[STR-8]}] V. Hern\'andez, J. E. Rom\'an, A. Tom\'as. ``Restarted Lanczos Bidiagonalization for the SVD in \slepc.''
\item[\textrm{\sffamily[STR-9]}] J. E. Rom\'an. ``Practical Implementation of Harmonic Krylov-Schur.''
\item[\textrm{\sffamily[STR-10]}] M. E. Hochstenbach, E. Romero, J. E. Roman. ``Davidson Type Subspace Expansions for the Linear Eigenvalue Problem.''
\item[\textrm{\sffamily[STR-11]}] Y. Maeda, T. Sakurai, J. E. Roman. ``Contour Integral Spectrum Slicing Method in \slepc.''
\end{list}
}

\cleardoublepage
\fancyhead{}\fancyhead[LO,RE]{\nouppercase{\scriptsize \sffamily Index}}
\addcontentsline{toc}{chapter}{Index}
\printindex
\cleardoublepage

\end{document}

